home *** CD-ROM | disk | FTP | other *** search
/ Risc World 3 / Risc World 3.iso / SOFTWARE / ISSUE4 / ZAP / !Zap / Modules / !ZapDWExt / !Help next >
Text File  |  2002-05-08  |  10KB  |  241 lines
  1. Modifications by sja, 14/9/98: the following commands have been removed since
  2. their functionality is duplicated elsewhere. This makes version 1.22.
  3.  
  4. CRLF        SWAPCRLF                ZapText
  5. FIRSTBLOCK    FINDSEL "first"                ZapText
  6. FINDBLOCK    FINDSEL "to buffer"            ZapText
  7. CLOSETBTW    DISCARDTHROWBACKS, DISCARDTASKWINDOWS    ZapUtil
  8. LINEEND        LINEENDS                ZapText
  9. SETNAME        SETNAME                    ZapUtil
  10. GOTOLINE    GOTOLINE, GOTOLINEP            ZapUtil
  11. GOTOADDR    GOTOADDRESS                ZapUtil
  12.  
  13. (Note that I haven't removed the code, just the references in the command
  14. table. HelpData and External files have been updated accordingly.)
  15.  
  16.     - sja, dj@zap.tartarus.org
  17.  
  18.  
  19.  
  20. ZapDWExt - an extension to Zap, (c) 1994-97 Daniel Wagenaar
  21. This text describes version 1.21
  22.  
  23. ZapDWExt does not provide any new modes.
  24.  
  25. ZapDWExt provides one *command: *Zap_Command. This command takes a filename
  26. and a colon-separated list of Zap commands for arguments. The file will be
  27. opened if necessary, the cursor will jump into it, and the commands will be
  28. executed.
  29.  
  30. It supports the following Zap commands:
  31.  
  32. BLOCKID        Blocks the identifier under the cursor. An
  33.         identifier is as defined by ANSI C, ie it starts with
  34.         a letter, and may contain numbers, letters, and the
  35.         underscore.
  36.  
  37. FIRSTBLOCK    Finds the first occurrence in the file of the marked
  38.         block.
  39.         
  40. DEFBLOCK    Finds ‘.<block>’ or ‘DEF<block>’ for BASIC or
  41.         ‘<block>(’ for C.
  42.  
  43. FINDBLOCK    Open a throwback window containing all occurrences of the
  44.         marked block.
  45.  
  46. FINDID        First do BLOCKID, then, if the mode is Basic, or the
  47.         mode is C and the first char after the block is '(',
  48.         do DEFBLOCK, else do FIRSTBLOCK. In this way, function
  49.         definitions may be found, and the first occurrence of a
  50.         variable may be found in C mode.
  51.  
  52. TLDBFILE    Finds the current selection as a top level definition in the
  53.         current file: in header files (in dir 'h.') function
  54.         declarations are found, in source files (in dir 'c.') only
  55.         definitions are found.
  56.  
  57. TLDBDIR        As TLDBFILE, but also searches parent directory.
  58.         If the directory is 'c.', 'h.' is searched as well.
  59.         If the directory is 's.', 'c.' and 'h.' are searched instead.
  60.         This command will often be used in the sequence
  61.         'BLOCKID:TLDBDIR:CLEARSEL'.
  62.         (In later version, absence of a selection may trigger prompt.)
  63.         (There is no automatic conversion between C++ file-directories
  64.         and their header-directories.)
  65.  
  66. TLDBHEAD    As TLDBDIR, but also searches through #includes.
  67.         This works for C only, but will, on demand, be extended to
  68.         assembly in a later version.
  69.  
  70. BLOCKSTAR    Do ‘*TaskWindow "<block>" -quit’, where <block> is the
  71.         selected area.
  72.  
  73. STARCOM        Does ‘*TaskWindow "<arg>" -quit’. <arg> may be
  74.         included in the Keys file, or typed in a mini-buffer.
  75.  
  76. CC        Compiles a C program using ‘STARCOM "cc <filename>"’.
  77.         It opens a minibuffer in which the command line
  78.         options may be specified. The default options are read
  79.         from and written to the system variable Zap$CCOptions.
  80.         As explained below, a default value may be assigned in
  81.         Zap's !Run file. A sensible default could be:
  82.         ‘-IC: -throwback -Lc:o.stubs,c:o.risc_oslib -Desktop ^’
  83.  
  84. MAKE        Makes a project using ‘STARCOM "prefix <dirname> |M amu -f
  85.         <leafname>"’. Additional command line options may be
  86.         specified via the minibuffer. Default options are read
  87.         from and written to the system variable Zap$AmuOptions.
  88.  
  89. ANYCOMPILE    Does ‘MAKE’ or ‘CC’, whichever is appropriate: for project
  90.         files do MAKE; for C files do CC, unless the string
  91.         'Makefile: <name> [<target>]' occurs near the start of the
  92.         text. In that case, MAKE is done, but no options are asked.
  93.         If a line of the form:
  94.           xxx +-+ <command> +-+ xxx
  95.         or:
  96.           xxx +-+ <command>
  97.         is found, then the command is executed instead of any
  98.         default action. In the command, the sequences %f, %l, %d
  99.         may be used to represent, respectively, the full filename,
  100.         the leafname, or the parent directory name of the file.
  101.         Example:
  102.          /* +-+ cc -IC: -Lc:o.stubs -throwback -Desktop ^ %f +-+ */
  103.  
  104. OPENMAKE    Opens the makefile for this project, if the string
  105.         ‘Makefile: <name>’ is included in the start of the
  106.         file.
  107.  
  108. OPENREF        Opens a file referenced at the cursor, eg for
  109.         #include <fff.h>. Note that OPENREF takes care of
  110.         path element inversion, as in ‘fff.h’ => ‘h.fff’.
  111.  
  112. OPENCH        Switches between C files and header files as follows:
  113.         If the file is named... OPENCH tries to open...
  114.         ‘...c.yyy’    ->    ‘...h.yyy’
  115.         ‘...cpp.yyy’    ->    ‘...h.yyy’ or ‘...hpp.yyy’
  116.         ‘...c++.yyy’    ->    ‘...h.yyy’ or ‘...h++.yyy’
  117.         ‘...cc.yyy’    ->    ‘...h.yyy’ or ‘...hh.yyy’
  118.         ‘...h.yyy’    ->    ‘...c.yyy’, ‘...cpp.yyy’,
  119.                     ‘...c++.yyy’ or ‘...cc.yyy’
  120.         ‘...hpp.yyy’    ->    ‘...cpp.yyy’
  121.         ‘...h++.yyy’    ->    ‘...c++.yyy’
  122.         ‘...hh.yyy’    ->    ‘...cc.yyy’
  123.  
  124. OPENOTHER    Does either OPENREF, OPENMAKE or OPENCH, whichever is
  125.         most appropriate. OPENOTHER uses the path ‘ZapDWS:’ to
  126.         complete filenames. For example, if a reference is made
  127.         to ‘stdio.h’, then OPENOTHER/OPENREF will try to open
  128.         ‘ZapDWS:h.stdio’. (As always, element inversion is taken
  129.         care of.) To make this system work, a line defining
  130.         ZapDWS$Path must be included in Zap's !Run file. See
  131.         below.
  132.  
  133. CLOSETBTW    Closes all throwback and task windows.
  134.  
  135. MODBRK        Sets a breakpoint in a module, at the cursor address.
  136.         The module must be loaded into Zap using 
  137.         
  138.           Create.Get module.<modname>
  139.           
  140.         and the filename must have remained unchanged. You must
  141.         be careful when using this command, because the computer
  142.         may crash if you set a breakpoint in a piece of code that
  143.         is used in IRQ mode. So: don't set breakpoints in the
  144.         UtilityModule unless you know what your doing :-)
  145.         In fact, MODBRK only works if the module in question
  146.         is in RMA. For ROM-based modules, you'd have to do a
  147.         *RMFaster before using MODBRK. This command is mainly
  148.         intended to be of use while debugging.
  149.  
  150. LINEEND        Replaces all occurrences of CRLF, CR, LF, LFCR by the
  151.         correct return character (as set in the ‘Display->
  152.         Misc->Return char->’ submenu). This is particularly
  153.         useful when you've copied a text file from an MS-DOS
  154.         system, which uses CRLF instead of plain LF.
  155.  
  156. CRLF        Exchanges CR <-> LF (Carriage returns with linefeeds).
  157.         This can be used to convert Mac style texts to Risc OS
  158.         style texts, or to convert spooled output (with LFCR)
  159.         to 'DOS style' text (CRLF) which can be converted to
  160.         ordinary Risc OS style texts by dragging them to the
  161.         Zap icon. This command has been written to replace
  162.         LINEEND where possible. It is *much* faster. CRLF can
  163.         not be undone using the UNDO command. It's action is
  164.         reversed by executing it again.
  165.  
  166. SETNAME        Sets the name of a file from an in-core filename.
  167.  
  168. REVERT        Reloads the current file from disc. This can be used in
  169.         two occasions: firstly if you have accidentally corrupted
  170.         your work and don't feel like pressing ‘Full undo’ a
  171.         million times. Secondly if an external program (such as
  172.         amu) has changed your file and you want to edit the
  173.         new version.
  174.  
  175. GOTOLINE    Alternative for F5 (GOTO), using the minibuffer. Thus it can
  176.         be used through *Zap_Command. The (string) argument is either
  177.         a logical line number, or 'P' followed by a physical line
  178.         number. Example in Basic:
  179.         ON ERROR OSCLI "Zap_Command this.file GOTOLINE "+STR$ERL:END
  180.         Also very useful for TeX users who don't have throwback at
  181.         their disposal.
  182.         If the argument is ‘!’ or the empty string, the system
  183.         variable ‘DWExt$LineNo’ is substituted.
  184.  
  185. GOTOADDR    As GOTOLINE, but goes to an address. If the command opens a
  186.         minibuffer, an hexadecimal sign ('&') is typed in for you.
  187.         No system variable substitution is performed.
  188.  
  189. DDEFIND        Searches for patterns in files, using ‘STARCOM "find -t
  190.         <args> >null:"’, ie calling the *-command ‘find’, producing
  191.         a throwback window (only).
  192.  
  193. In addition to the Zap commands, there is a single *-command:
  194. *Zap_Command. This may be used to call Zap commands from an external
  195. task. Its syntax is: *Zap_Command <filename> <commands>. The file is
  196. loaded if it isn't already in memory. There may be more than one
  197. command, separated by colons as in the ‘Keys’ file. See the example
  198. under GOTOLINE.
  199. Note that this command is currently in beta-release. It doesn't seem
  200. to do terrible things, but sometimes the display update isn't very
  201. nice, particularly when called from a task window.
  202.  
  203. I hope these commands may be of use to other people.
  204. As I distribute ZapDWExt free of charge, I cannot take any
  205. responsibility for any damage caused by using or the inability to use
  206. it. In particular, I don't give any guarantee that it will leave your
  207. texts intact. That said, I believe I've tested it rather thoroughly,
  208. and to my knowledge, it is bug-free. There may be features, though :-)
  209. If you do encounter any bugs, or unexpected behaviour, or if you have
  210. any comments, please contact me:
  211.  
  212.     Daniel Wagenaar
  213. snail:  Burmanstraat 32'
  214.     1091 SK  Amsterdam
  215.     The Netherlands
  216. tel.:    +31-(20)-4634883
  217. e-mail: dwagenr@phys.uva.nl (preferred)
  218.  
  219. Any feedback is highly welcome!
  220.  
  221. Finally...
  222.  
  223. ZapDWExt will only run under Risc OS 3, mainly because Risc OS 2 can't
  224. complete pathnames. If anybody urgently wants to run ZapDWExt under
  225. Risc OS 2, then I hope someone will have a replacement for
  226. OS_FSControl with r0=37, or else I may have to write something...
  227.  
  228. I agree that the documentation for ZapDWExt is rather terse. This is
  229. because it originally served only as a post-it note to myself, to
  230. enable me to remember the commands... On popular demand I'll write
  231. more extensive docs. Also, if you feel these commands lack
  232. universality, and have an idea to improve them, do let me know.
  233.  
  234. Versions
  235. --------
  236. 1.22 Modifications by sja, 14/9/98 as listed above.
  237. 1.21 Bug fix release: A bug in ZapSoftWrap made me notice that Zap calls
  238.      return with R0 corrupted.
  239. 1.20 This version history starts here. Earlier versions had less commands,
  240.      and more bugs...
  241.